ReadMe.txt for
AppleShell.zip
By Bill Buckels September 2008

This ZIP file contains diskimages and documentation for 2 versions of
the Aztec C SHELL for the Apple II; a ProDOS 8 Version and a DOS 3.3
version. I have configured both SHELL programs to run in 80 column
mode. One of the strongest features of these is the support for
different standard hardware of the day as well.

These diskimages and the other contents of this ZIP file were produced
as a mini-project of sorts to explore the use of both SHELL programs
which provide a decidedly unix-like flavour to the Apple II.

Not only are many of the unix commands supported, but also each SHELL
has its own unique strengths, some which I will mention now.

The ProDOS SHELL.SYSTEM uses paths to navigate, and further the SHELL
has a resident and transient portion that is similar to what one would
have expected back in the MS-DOS days of TSR programs. If you don't
know about those, suffice to say that the ProDOS SHELL unloads itself
to run external programs and reloads itself when done (in most cases).

Another important feature of the ProDOS SHELL.SYSTEM is that since it
can be copied to the RAM disk on an Apple //e it will load itself back-
in from RAM leaving the 2 disk drives open for program and data disks.

The DOS 3.3 shell tackles efficient use of the limited resources on an
Apple II by supporting very tiny PCODE programs.

Please read each's respective documentation for additional details. I
am not going into exhaustive detail about the use of the SHELL. For the
DOS 3.3 version; see the text file D33Shell.txt and for the ProDOS
version see SHELLC65A.PDF. The sample program source code can also be
reviewed for additional details.

And please remember that like unix, these SHELL programs are case-
sensitive and expect lower-case for their internal commands. SHELL
scripting is also supported in both and a surprising myriad of
additional features considering the relative size of these and the
small memory footprint of the Apple II.

ProDOS Diskimages
-----------------

ProShellA.dsk /SYSTEM:

debwr SYS (2000)    25600 Jun 18 00:00   filer
debwr SYS (2000)    14848 Jun 10 12:37   prodos
debwr TXT (0000)      153 Aug 17 10:19   profile
debwr SYS (2000)    27044 Jun 27 15:42   shell.system

ProShellB.dsk /UTIL:

debwr PRG (0800)    20236 Nov 13 20:15   diff
debwr PRG (0800)    10440 Aug 19 01:18   exmpl
debwr TXT (0000)      177 Aug 19 02:31   exmpl.c
debwr PRG (0800)    19336 Sat  0 00:00   grep
debwr PRG (0800)    11130 Aug 19 21:04   lcase
debwr TXT (0000)     1467 Aug 19 23:21   lcase.c
debwr PRG (0800)    11242 Aug 26 22:03   more
debwr TXT (0000)     2297 Aug 31 06:48   more.c
debwr PRG (0800)    12426 Aug 24 22:58   sort
debwr TXT (0000)     2200 Aug 31 06:48   sort.c
debwr PRG (0800)    11130 Aug 19 19:41   ucase
debwr TXT (0000)     1468 Aug 19 23:25   ucase.c

Navigation
----------

To navigate the ProDOS shell put the SYSTEM disk in drive 1 and the
UTIL disk in drive 2. Boot the SYSTEM disk. Make sure your CAPS lock is
off. To change to drive 2 type "cd /UTIL" and press [RETURN]. To change
to the RAM disk, type "cd /RAM" and press [RETURN].

For those serious-minded individuals who dare to tread on the metal.

The pdf manual for the ProDOS SHELL describes the SHELL's file system
showing the hierarchy beginning with the "root" directory. The "root"
directory is specified with a slash (a forward slash like in unix
pathnames, and not a backslash like in MS-DOS and Windows Network
pathnames).

Therefore to change directory to the root, type "cd /" and press
[RETURN].

As implied above, you need some way of knowing the PREFIX when you put
a new disk in the drive so you can change to it using the SHELL's
directory metaphor. The manual is not clear on this. When you type "ls
/SYSTEM" and press [RETURN] all the files (and sub-directories if any)
on the disk with the SYSTEM volume label are listed (sub-directories
if any are preceded with a dash). However when you type "ls /" or when
you type "ls" when in the virtual "root" directory, nothing is listed.

What do you do now? Keep in mind that you are in "SHELL HELL" and
you can't TAB around like you can in the ProDOS finder. You may as
well be in linux:) without the KDE or X of any kind. 

The manual also discusses the use of wildcards (the asterisk) and the
use of the ls internal SHELL command, but one important and very
significant detail has been missed... Read-on.

To list all volumes simply type "ls /*" and press [RETURN].

Another tip: Removing a sub-directory:

To make a sub-directory on the current volume, as expected, "mkdir
myfolder" and press [RETURN]. To change to the new directory the cd
command works. There is no rmdir command to remove a sub-directory.
Just use the rm command.

A Final tip: To see what's on path (set in the SHELL profile):

echo $PATH

DOS 3.3 Diskimages
------------------

D33Shell.dsk
D33Compiler.dsk
D33Filters.dsk

To navigate the DOS 3.3 shell put the D33Shell disk in drive 1 and the
D33Filters disk in drive 2. Boot the D33Shell disk. Make sure your CAPS lock is
off. To change to drive 2 type "cd d2" and press [RETURN]. To change
back to drive 1, type "cd d1" and press [RETURN]. To get a directory 
listing type "ls" and press [RETURN].

Note that while the ProDOS Shell uses proper pathing with PREFIXs the
DOS 3.3 Shell just uses d1 and d2 as its PATH.

What's Included
---------------

Some additional utilities are included with both versions and an Aztec
C native mode compiler environment is included on the diskimages for
the DOS 3.3 version.

I have written and compiled several filter programs and a "hello world"
program for use with each shell. The source code is identical, however
the executables are targeted at their particular SHELL. The programs
targeted at the DOS 3.3 shell are very tiny. Neither the ProDOS nor the
DOS 3.3 sample programs will run properly outside their intended SHELL
since both environments are SHELL version and OS version specific and
all accept command line arguments. The filter programs will also accept
redirected input and output and file input.

These sample programs are compiled to PCODE (pseudo-code) and run
somewhat slower than native code, but with the availbility of
emulators, CF drives and accelerators that increase execution speed
over what was then available, their performance is quite acceptable.

The ProDOS samples were compiled in the CG65 cross-development
environment available for download from the Aztec C website at:

http://www.aztecmuseum.ca/AZCG65.zip

The DOS 3.3 samples were compiled on the diskimage provided in this ZIP
file using the native mode compiler also provided on the diskimage in
this ZIP file. To my knowledge, no cross-development environment exists
for the DOS 3.3 Aztec C SHELL.

Building Shell Programs for DOS 3.3 in the Aztec C Shell
--------------------------------------------------------

There are 3 DOS 3.3 diskimages in this ZIP file:

D33Shell.dsk
D33Compiler.dsk
D33Filters.dsk

To build DOS 3.3 programs that will run in the Aztec C DOS 3.3 Shell,
boot with the D33Shell.dsk in drive 1 then put the D33Filters.dsk in 
drive 2  and the D33Compiler.dsk in drive 1. 

Type "cd d2" and press [RETURN] to change to drive 2.

Then type "ls" and press [RETURN] to list the directory. A number of
C source files are listed.

Type "MAKEFILE exmpl" and press [RETURN] to build the EXMPL program.
Repeat as necessary.

It took 11 seconds to build EXMPL from exmpl.c in its entirety under
DOS 3.3. in the AppleWin emulator on my AMD DX2/3000 Windows XP
machine. More capable machines may get faster results.

MAKEFILE
--------

MAKEFILE is a SHELL script on the DOS 3.3 compiler disk:

x--- snip ---x
set -x -a
loop
# Now Building $%
cci $%.c
ln $%.INT SHINT.LIB
rm $%.INT
loop
x--- snip ---x

It is used to build any old thing by using the basename of the C
program as an argument. It is pretty much right out of the Aztec C
manual. 

It can also be used to build multiple files.

For example:

MAKEFILE exmpl ucase lcase

will build all 3 programs. The loop keywords in the DOS 3.3 shell
script which enclose the build sequence will shift up to 9 source 
filenames named on the command line and compile each in succession.

Acknowledgements
----------------

Thanks to Rubywand (Jeff Hurlbert) for his work in organizing the DOS
3.3 AztecC_minimanual.txt from which D33Shell.txt (the DOS 3.3 Shell
Documentation) is excerpted.

Thanks to Paul Santa-Maria for making the PDF manual MANXC65A.pdf
available for download from sys.apple2 from which the ProDOS SHELL
documentation is excerpted from. Thanks to Dean Phares for splitting
the SHELL chapter out of the PDF and keeping it small.

Thanks also to Paul Santa-Maria for making the CG65 compiler and its
docs available.

And thanks to the other folks on comp.sys.apple2 and
comp.sys.apple2.programmer for the good discussions that have provided
the details I needed and the other bits and pieces to pull this Aztec C
Stuff and this little SHELL project together.

Bill Buckels
September 1988.

End of Document
